home *** CD-ROM | disk | FTP | other *** search
/ Compendium Deluxe 1 / LSD Compendium Deluxe 1.iso / a / intuition / menu / popupm10.lha / PopUpMenuClass_1.0 / docs / PopUpMenuClass.notes < prev   
Encoding:
Text File  |  1993-12-23  |  8.1 KB  |  230 lines
  1.  
  2.                              PopUpMenuClass
  3.                              ~~~~~~~~~~~~~~
  4.  
  5.                      Release:       1.0   (23.12.1993)
  6.                       Author:       Markus Aalto
  7.  
  8.  
  9. COPYRIGHT
  10. ~~~~~~~~~
  11.  
  12.     PopUpMenuClass BOOPSI object for AmigaDOS V37 or greater.
  13.     Copyright (C) 1993  Markus Aalto
  14.  
  15.     This program is free software; you can redistribute it and/or modify
  16.     it under the terms of the GNU General Public License as published by
  17.     the Free Software Foundation; either version 1, or (at your option)
  18.     any later version.
  19.  
  20.     This program is distributed in the hope that it will be useful,
  21.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  22.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  23.     GNU General Public License for more details.
  24.  
  25.     You should have received a copy of the GNU General Public License
  26.     along with this program; if not, write to the Free Software
  27.     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  28.  
  29.     You can contact the author by writing to Markus Aalto,
  30.     Muurahaisentie 11a, 01490 VANTAA, FINLAND. Or send EMail to
  31.     s37732v@vipunen.hut.fi.
  32.  
  33.  
  34.  
  35. INTRODUCTION
  36. ~~~~~~~~~~~~
  37.  
  38.     This is a documentation for PopUpMenu gadget class. This gadget
  39.     class is implemented as a subclass of "gadgetclass" BOOPSI class.
  40.     Therefore it inherits all the qualities of its parent supporting
  41.     things like disabling, relative positions and relative dimensions.
  42.  
  43.     PopUpMenu gadget is based on a idea of Cycle and ListView gadget.
  44.     Cycle gadgets are nice because they don't take too much space
  45.     in GUI but are a pain if there are many options to choose from.
  46.     The ListView gadget is much nicer but it takes a lot of space.
  47.     The solution which is existed in a many other platforms earlier
  48.     is a concept of PopUpMenu gadgets which open up a Menu when
  49.     gadget is pressed and this is exactly what PopUpManuClass now
  50.     brings to the use of Amiga users.
  51.  
  52.     Because there is always room for improvement in any program there
  53.     is also in this class, but for now it does its job quite nicely.
  54.     If you feel the need to continue the effort I have started, please
  55.     feel free to implement it further. I would like to get the changes
  56.     however because I intend to do further developing of my own too.
  57.  
  58.     For those of you who think this is breaking the concept of User
  59.     Style Guide conforming programming I want to say that I have tried
  60.     to conserve the look/feel of AmigaOS in a behaviour of this gadget.
  61.     Because Commodore haven't offered this solution I think that this
  62.     is a very good substitution until they do cover this area in future
  63.     OS releases (I hope). Also I don't think that it's necessary to
  64.     follow exactly all the steps the Style Guide represents. In my
  65.     opinion they should be used as a guide line, which you should try
  66.     to follow in those parts of the programming where it's feasible
  67.     or possible at all.
  68.  
  69.  
  70.  
  71. FUNCTION
  72. ~~~~~~~~
  73.  
  74.     PopUpMenuClass link-time library consists of 2 public functions
  75.     user can call. These are explained in detail in PopUpMenuClass.doc.
  76.  
  77.     CreatePopUpMenuClass() function is used to create a private subclass
  78.     of 'gadgetclass'- It returns a pointer to this newly created class
  79.     so that you can use NewObject() system call to create your own objects.
  80.  
  81.     DisposePopUpMenuClass() is the function user have to call to free the
  82.     resources allocated by CreatePopUpMenuClass(). Call it when you are
  83.     done using PopUpMenuClass.
  84.  
  85.  
  86.  
  87. ATTRIBUTES
  88. ~~~~~~~~~~
  89.  
  90.     The tags recognized by the PopUpMenu gadget class are.
  91.  
  92.     PUMG_Labels (List *)
  93.         A Pointer to standard Exec List, where ln_Name fields point to
  94.         displayed item names. If the item list is empty then empty List
  95.         structure or NULL pointer can be used. This tag also accepts
  96.         a tag value of ~0, which means that OM_SET method doesn't
  97.         return a non-null value, to indicate that gadget shouldn't
  98.         be refreshed. This is a good way to detach a list while modifying
  99.         it. Default is NULL.
  100.         (Create, Set, Get.)
  101.  
  102.     PUMG_Active (UWORD)
  103.         The ordinal number, counting from zero, of the active choice
  104.         of the gadget. Default is zero.
  105.         (Create, Set, Get, Update, Notify.)
  106.  
  107.  
  108.     PUMG_TextFont (TextFont *)
  109.         A Pointer to opened TextFont for Gadget Text/PopUpMenu to
  110.         use. If this is NULL then default RastPort font returned
  111.         with GM_RENDER method is used.
  112.         Default is NULL.
  113.         (Create, Set, Get.)
  114.  
  115.     GA_Disabled (BOOL)
  116.         Set this attribute to TRUE to disable PopUpMenu, to FALSE
  117.         otherwise. Default is FALSE. Note that Gadget isn't updated
  118.         automatically. Instead it SetGadgetAttrs() returns you
  119.         non-NULL value, which means that you should do the refreshing.
  120.         (Create and Set.)
  121.  
  122.  
  123.  
  124. POPUPMENUCLASS GADGET DIMENSIONS
  125. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  126.  
  127.     There are no predefined dimensions for PopUpMenu gadget. The
  128.     width should be atleast 28 pixels (PUMG_MinWidth), and height
  129.     should be atleast 8 pixels (PUMG_MinHeight). This gadget knows
  130.     how to handle the strings wider than the gadget. However it
  131.     doesn't try to clip texts higher than the gadget, so use
  132.     the font height (tf->tf_YSize + INTERHEIGHT) to give a good look
  133.     for the gadget. (INTERHEIGHT is a predefined system value for
  134.     GadTools gadgets.)
  135.  
  136.  
  137.  
  138. KEYBOARD OPERATION
  139. ~~~~~~~~~~~~~~~~~~
  140.  
  141.     You can also use keyboard to control the PopUpMenu gadget. Gadget
  142.     can be activated from a program by ActivateGadget() intuition
  143.     call. You can use following keyboard commands to control menu.
  144.  
  145.         CURSOR-UP           - Move up in a menu.
  146.         CURSOR-DOWN         - Move down in a menu.
  147.         ALT-CURSOR-UP       - Move start of a menu list.
  148.         ALT-CURSOR-DOWN     - Move end of the menu list.
  149.         RETURN              - Select item.
  150.         ESC                 - Escape menu.
  151.  
  152.  
  153.  
  154. ATTRIBUTE SETTINGS
  155. ~~~~~~~~~~~~~~~~~~
  156.  
  157.     If you want to have a automatic update for a gadget, when you
  158.     call SetGadgetAttrs() you should use following functions
  159.     instead of SetGadgetAttrs().
  160.  
  161.     void New_SetGadgetAttrsA( struct Gadget *gadget,
  162.                               struct Window *window,
  163.                               struct Requester *req,
  164.                               struct TagItem *tags )
  165.     {
  166.         if( SetGadgetAttrsA( gadget, window, req, tags) ) {
  167.             RefreshGList( gadget, window, req, 1);
  168.         }
  169.     }
  170.  
  171.     or
  172.  
  173.     void New_SetGadgetAttrs( struct Gadget *gadget,
  174.                              struct Window *window,
  175.                              struct Requester *req,
  176.                              ULONG item, ... )
  177.     {
  178.         New_SetGadgetAttrsA( gadget, window, req, (struct TagItem *)&item);
  179.     }
  180.  
  181.  
  182.  
  183.  
  184. NOTES
  185. ~~~~~
  186.  
  187.     PopUpMenuClass.lib needs following libraries to be open:
  188.     graphics.library, intuition.library and utility.library. All
  189.     version 37 or greater of course.
  190.  
  191.     If SetGadgetAttrs() returns anything else than 0 (when setting
  192.     atrributes for PopUpMenu gadget) you should call intuition
  193.     gadget refresh functions.
  194.  
  195.  
  196.     ********************** WARNING WARNING ***********************
  197.  
  198.     If you use gadget's ID value to identify your PopUpMenu gadget
  199.     then do not let other Boopsi gadgets send GA_ID messages to
  200.     your gadget. You can prevent this by using Map tags and mapping
  201.     GA_ID to TAG_IGNORE. This is possibly a bug in 'gadgetclass'
  202.     BOOPSI class because 'OM_UPDATE' methods should not change GA_ID
  203.     values - or at least RKM says it shouldn't.
  204.  
  205.     ********************** WARNING WARNING ***********************
  206.  
  207.  
  208.     If you want to hear the gadget Active item changes, then you have
  209.     2 possibilities.
  210.  
  211.         Listen to IDCMP_GADGETUP messages for changes and get the new
  212.         Active value from Code field of IntuiMessage structure.
  213.         Remember to set GA_RelVerify for the gadget.
  214.  
  215.         Listen to IDCMP_IDCMPUPDATE message for changes. The returned
  216.         TagList contains GA_ID and PUMG_Active.
  217.  
  218.  
  219.  
  220.  
  221. BUGS
  222. ~~~~
  223.  
  224.     Doesn't scroll the list if there is more items than fits to the
  225.     screen. Is it even necessary?
  226.  
  227.     Should work if put to window borders, but the colors won't look
  228.     right.
  229.  
  230.